IDLitComponent::RegisterProperty

The IDLitComponent::RegisterProperty procedure method registers a property as belonging to the component. Only registered properties are displayed in the graphical property sheet interface for the object.

Obj->[IDLitComponent::]RegisterProperty, PropertyIdentifier[, Type] [, /ADVANCED_ONLY] [, /BOOLEAN] [, /COLOR] [, DESCRIPTION=string] [, ENUMLIST=stringvector] [, /FLOAT] [, /HIDE] [, /INTEGER] [, /LINESTYLE] [, NAME=string] [, /SENSITIVE] [, /STRING] [, /SYMBOL] [, /THICKNESS] [, /UNDEFINED] [, USERDEF=string] [, VALID_RANGE=vector]

PropertyIdentifier

A scalar string containing the property identifier. GetProperty and SetProperty methods accept this string as a keyword.

Type

An optional integer argument representing the property type. Values recognized by Property Sheets are:

• 0 = USERDEF
• 1 = BOOLEAN
• 2 = INTEGER
• 3 = FLOAT
• 4 = STRING
• 5 = COLOR
• 6 = LINESTYLE
• 7 = SYMBOL
• 8 = THICKNESS
• 9 = ENUMLIST

If Type is not supplied, then one of the type keywords must be set instead.

Note: Properties registered as Type 2 (Integer) can contain integers up to 64-bits.

Keywords

Some of the following keywords correspond to attributes of the property being registered. Keywords followed by the word “Get” indicate attributes that can be retrieved by the IDLitComponent::GetPropertyAttribute method. Keywords followed by the word “Set” indicate attributes that can be set by the IDLitComponent::SetPropertyAttribute method.

Some of the following keywords correspond to iTool property data types, which can also be specified via the Type argument. Note that if both the Type argument and one of the corresponding keywords are set, the keyword value will be honored.

ADVANCED_ONLY

Set this keyword to indicate that the property should be marked as ADVANCED_ONLY. Properties marked ADVANCED_ONLY do not display in the simple view of the property sheet, but are displayed in the advanced view.

BOOLEAN

Set this keyword to indicate that the property type is BOOLEAN. Properties of type BOOLEAN must accept an integer value of either 0 (“False”) or 1 (“True”). Setting this keyword is equivalent to setting the TYPE argument equal to 1.

COLOR

Set this keyword to indicate that the property type is COLOR. Properties of type COLOR must accept a three-element integer array containing an RGB triplet. Setting this keyword is equivalent to setting the TYPE argument equal to 5.

DESCRIPTION

(Get, Set)

Set this keyword to a string containing the description of this property.

Note: Do not confuse the DESCRIPTION property attribute with the DESCRIPTION property. The DESCRIPTION property attribute is not displayed in the graphical property sheet interface.

ENUMLIST

(Get, Set)

Set this keyword equal to an array of strings to be displayed in the dropdown menu displayed by a property of type ENUMLIST. The default is a scalar null string. Properties of type ENUMLIST report their value as an integer between 0 and n‑1, where n is the number of elements in the enumerated list. Setting this keyword implies that the TYPE argument is equal to 9.

FLOAT

Set this keyword to indicate that the property type is FLOAT. Properties of type FLOAT must accept a scalar double-precision floating-point value. Setting this keyword is equivalent to setting the TYPE argument equal to 3.

HIDE

(Get, Set)

Set this keyword to hide the given property when displaying the graphical property sheet interface. By default, all registered properties are displayed.

INTEGER

Set this keyword to indicate that the property type is INTEGER. Properties of type INTEGER must accept a scalar integer value (up to 64-bit integers). Setting this keyword is equivalent to setting the TYPE argument equal to 2.

LINESTYLE

Set this keyword to indicate that the property type is LINESTYLE. Properties of type LINESTYLE must accept an integer specifying a pre-defined linestyle, as described under the LINESTYLE property of the IDLgrPolyline class. Setting this keyword is equivalent to setting the TYPE argument equal to 6.

NAME

(Get, Set)

Set this keyword to a string giving the human-readable name for the property. The NAME string will be used when displaying the graphical property sheet interface. If NAME is not set, the value of the PropertyIdentifier argument is used.

Note: Do not confuse the NAME property attribute with the NAME property.

SENSITIVE

(Get, Set)

Set this keyword to zero to make the given property insensitive in the graphical property sheet interface. By default, registered properties are sensitive.

STRING

Set this keyword to indicate that the property type is STRING. Properties of type STRING must accept a scalar string of any length. Setting this keyword is equivalent to setting the TYPE argument equal to 4.

SYMBOL

Set this keyword to indicate that the property type is SYMBOL. Properties of type SYMBOL must accept an integer specifying one of the pre-defined symbol types described under IDLgrSymbol::Init. Setting this keyword is equivalent to setting the TYPE argument equal to 7.

THICKNESS

Set this keyword to indicate that the property type is THICKNESS. Properties of type THICKNESS must accept an integer between 1 and 10 specifying the line thickness in points. Setting this keyword is equivalent to setting the TYPE argument equal to 8.

UNDEFINED

(Get, Set)

Set this keyword to indicate that the property should appear as a blank cell when displayed in the graphical property sheet interface. This is useful in situations where properties of multiple objects are displayed in the property sheet (either because multiple objects are selected, or because the objects have been grouped).

Note: It is the iTool developer’s responsibility to set this property attribute back to zero. Use the SET_DEFINED field of the WIDGET_PROPERTYSHEET event structure to determine when to set the UNDEFINED attribute back to zero.

USERDEF

(Get, Set)

Set this keyword to a string that represents a user-defined property. Properties of type USERDEF can accept and return variables of any type. When the actual property value changes, it is assumed that the string value of the USERDEF attribute will also be modified to reflect the new property value. Setting this keyword implies that the TYPE argument is equal to 0.

VALID_RANGE

(Get, Set)

For INTEGER or FLOAT types, set this keyword to a two- or three-element vector specifying the [minimum, maximum] or [minimum, maximum, increment] for valid values of the property.

What is displayed for the property sheet number cell depends upon the following:

• If this attribute is not specified: The property sheet displays an editable text field where masked editing is enforced, and the range is that of the data type. The only accepted keystrokes are the ten digits and the plus and minus signs. If the float type is specified, the decimal, and “d” and “e” (scientific exponent notation tokens) are also allowed.
• If a range is specified without an increment: The property sheet displays a spinner control that allows the user to click, or click and hold the up or down buttons to change the value. For an integer type, the increment is one. For a float type, the increment equals approximately 1/100 of the range. For example, a range of 100 results in an increment of 1. A value is snapped to the nearest allowable value when a value outside the range, or not equal to an incremental value, is entered. The editable text field (featuring masked editing) also allows the user to enter a numerical value.
• If a range and increment are specified: The property sheet displays a slider with a marker that can be repositioned to change the value. A value is snapped to the nearest allowable value when a value outside the range, or not equal to an incremental value, is entered. The increment value must be positive and will be converted to an integer for INTEGER types. Specifying an increment of 0 (zero) is the same as specifying a range without an increment. The editable text field (featuring masked editing) also allows the user to enter a numerical value.

The following code creates properties containing various number cells:

; Number cell with no explicit range.

self->RegisterProperty, 'integer1', /INTEGER , $

   NAME = 'Integer1', description = 'Integer'

 

; Number cell with spinner control and explicit range.

self->RegisterProperty, 'integer2', /INTEGER , $

   NAME = 'Integer2', VALID_RANGE = [ -100, 100 ]

 

; Number cell with slider control, explicit range, and

; increment.

self->RegisterProperty, 'float1', /FLOAT, $

   NAME = 'Float1', VALID_RANGE = [ -20.0D, 5.0D, 0.5D ]

Version History

6.0	Introduced
6.1	Added spinner control functionality to VALID_RANGE keyword

See Also

IDLitComponent::QueryProperty, IDLitComponent::UnregisterProperty